---
title: 'Update Theme'
description: 'Update astro theme pure to the latest version'
order: 1
---

import { Aside } from 'astro-pure/user'

<Aside type='caution'>
  This theme is updated frequently, and updating the theme may be a little bit complex. Please read
  the following breaking changes carefully.
</Aside>

## Breaking Changes

### v4.0.8

No breaking changes.

### v4.0.7

- Changed the `Button` component to use `variant` prop instead of `style` prop. This can help you add custom styles without conflicts. You should change your code like this:

  ```jsx
  <Button title='My Button' style='primary' /> // [!code --]
  <Button title='My Button' variant='primary' /> // [!code ++]
  ```

- Changed the `ExternalLinks` configuration in `src/site.config.ts`. You should change your config like this:

  ```ts title="src/site.config.ts"
  export const theme: ThemeUserConfig = {
    content: {
      externalLinksContent: ' ↗', // [!code --]
      /** External links configuration */ // [!code ++]
      externalLinks: { // [!code ++]
        content: ' ↗', // [!code ++]
        /** Properties for the external links element */ // [!code ++]
        properties: { // [!code ++]
          style: 'user-select:none' // [!code ++]
        } // [!code ++]
      }, // [!code ++]
      /** Blog page size for pagination (optional) */
      blogPageSize: 8,
      externalLinkArrow: true // show external link arrow // [!code --]
    }
  }
  ```

  - Changed the Waline files out of package! Checkout [Commit 5119694](https://github.com/cworld1/astro-theme-pure/commit/5119694ab3e32b600887dca30650bcbc63da3f7b) to see how to change your existing pages & layouts. Don't forget to copy files at `src/components/waline` to your project.

### v4.0.6

- Changed the project card var name to `projects` instead of `project`.

### v4.0.5

- Changed the UnoCSS preset from `Wind3` to `Mini`. Some features are removed, like `gradient`, `animation`, `container`, etc.

### v4.0.3

- Changed footer registration config to `links`. This will give you more flexibility to add more links or other information:

  ```ts title="src/site.config.ts"
  export const theme: ThemeUserConfig = {
    footer: {
      links: [ // [!code highlight:12]
        {
          title: 'Moe ICP 114514',
          link: 'https://icp.gov.moe/?keyword=114514',
          style: 'text-sm' // Uno/TW CSS class
        },
        {
          title: 'Site Policy',
          link: '/terms/list',
          pos: 2 // position set to 2 will be appended to copyright line
        }
      ]
    }
  }
  ```

### v4.0.2-beta

- Consider moving tool icons to a new path such as `src/assets/tools/`; this may help users know which ones are relevant to tools.
- Changed links `applyTip` to a custom array style:

  ```ts title="src/site.config.ts"
  export const integ: IntegrationUserConfig = {
    links: {
      applyTip: [
        { name: 'Name', val: theme.title }, // [!code highlight:4]
        { name: 'Desc', val: theme.description || 'Null' },
        { name: 'Link', val: 'https://astro-pure.js.org/' },
        { name: 'Avatar', val: 'https://astro-pure.js.org/favicon/favicon.ico' }
        // You can also add more fields
      ]
    }
  }
  ```

- Add the env variable `BUN_LINK_PKG`. Set this to `true` to automatically refer to the package `astro-pure` in the path `packages/pure` instead of `node_modules/astro-pure`. This may help users develop the theme or change code for themselves (not recommended for production).
- Changed the CSS framework to UnoCSS. This will affect `unocss.config.ts` and typography class name settings.

### v4.0.1-beta

- Changed svg deliver import to custom import svg element. This will affect using component for `ToolSelection`. You should change:

  (Optional) Move icons to new path like `src/assets/icons/`

  Then change using code (default at `src/pages/about/index.astro`)

  ```ts title="src/pages/about/index.astro"
  <ToolSection
    tools={[
      {
        name: 'Arch Linux',
        description: 'Linux Distribution',
        href: 'https://archlinux.org/',
        iconPath: 'archlinux' // [!code --]
        icon: import('@/assets/icons/archlinux.svg?raw') // [!code ++]
      }
    ]},
  />
  ```

- This changes import a new component `Svg`. See [User Components #Svg Loader](/docs/integrations/components#svg-loader) for usage.

### v4.0.0-alpha

- Move all components, types and utils that are reused to new npm packages `astro-pure`. Affected components are included in . Import method is also changed:

  ```ts
  import { Button } from '@/components/user' // [!code --]
  import { Button } from 'astro-pure/user' // [!code ++]
  ```

- New format config file `src/site.config.ts`. There will be zod schema to validate the config file, and use of config will be changed to:

  ```ts
  import { siteConfig } from '@/site-config' // [!code --]
  import config from '@/site-config' // [!code ++]
  // Or if you want to use the config that is after processed or transformed
  import config from 'virtual:config' // [!code ++]
  ```

- Built-in astro config supported. package `astro-pure` will automatically config some integrations like `unocss/astro`, `@astrojs/mdx`, `@astrojs/sitemap`, also with some rehypePlugins and remarkPlugins.
- Changed search engine to [pagefind](https://pagefind.app/), mainly because Astro v5 will not allow getting collection data directly from client (that is core working mode of Fuse.js search engine).
- Changed some `BaseHead` tags config to `src/site.config.ts`.

### v3.1.4

- Move config `siteConfig.content.typographyProse` to `integrationConfig.typography.class` in `src/site.config.ts`.
- Move advanced components to `src/components/advanced`. Affected components are included in [Advanced Components](/docs/integrations/advanced). Import method is also changed:

  ```ts
  import LinkPreview from '@/components/LinkPreview.astro' // [!code --]
  import { LinkPreview } from 'astro-pure/advanced' // [!code ++]

  <LinkPreview href='https://www.cloudflare.com/' />
  ```

- Move `Substats` config to related page `src/pages/about/index.astro`.
- Changed Github Card component to `GithubCard` in `src/components/advanced`. See [Advanced Components #Github Card](http://localhost:4321/docs/integrations/advanced#github-card) for usage.
- Move Links Logbook to `src/site.config.ts`. See [Friend Links #Basic Configurations](/docs/integrations/links#basic-configurations).

### v3.1.3

- Move user components to `src/components/user`. Affected components are included in [User Components](/docs/integrations/components). Import method is also changed:

  ```ts
  import Button from '@/components/Button' // [!code --]
  import { Button } from 'astro-pure/user' // [!code ++]
  ```

- Replace `remark-github-blockquote-alert` plugin to component `Aside`. Check [User Components #Aside](/docs/integrations/components#aside) to know how to migrate.

### v3.1.2 (pre-release)

- Move some configuration items like `telegram`, `walineServerURL` to new structure in `src/site.config.ts`.

### v3.1.1

- Move the internal parts in the `src/utils` to `src/plugins`.
- Modify the configuration file `astro.config.ts` to `astro.config.mjs`.
- Update ESLint to latest version and migrate configuration file `.eslintrc.js` to `eslint.config.mjs`.
- Modify the `prettier.config.js` to `prettier.config.mjs`.

### v3.1.0 (pre-release)

- Changed common content markdown formatter `coverImage` to `heroImage`. You need to modify all your markdown files to replace `coverImage` with `heroImage`.

### v3.0.9

A stable version.

Pending update...

## Update Method

### Rebase

If you create a new project using fork, you can just rebase the theme repository to the latest version.

### Merge Manually

As the git histories are not the same, you might need to merge the theme repository into your project manually.

A practical way for Windows users is to use the tool [WinMerge](https://winmerge.org/).

A filter list may be helpful:

```diff
## This is a directory/file filter template for WinMerge
name: Astro Theme Pure
desc: Diff for Blog v.s. Astro Theme Pure

## Select if filter is inclusive or exclusive
## Inclusive (loose) filter lets through all items not matching rules
## Exclusive filter lets through only items that match to rule
## include or exclude
def: include

## Filters for filenames begin with f:
## Filters for directories begin with d:
## To exclude some of the files that match the f: pattern, specify f!:
## To exclude some of the folders that match the d: pattern, specify d!:
## (Inline comments begin with " ##" and extend to the end of the line)

### Front-end files ###
d: \\\.git$
d: \\node_modules$

# Astro cache
d: \\\.vercel
d: \\\.astro

### Theme dev ###
d: ^\\packages$
d: ^\\preset$
d: ^\\test$
f: ^LICENSE$
f: ^README\.md$
f: ^README-zh-CN\.md$
f: ^CODE_OF_CONDUCT\.md$

# Project
f: ^bun\.lockb$
f: \.code-workspace$
f: ^ignore\.md$

### Astro theme pure ###
# Static
d: ^\\public\\favicon$
f: ^public\\links\.json$
f: ^public\\images\\social-card\.png$

# Assets
f: ^src\\assets\\avatar\.png$
d: ^\\src\\assets\\projects$
d: ^\\src\\assets\\tools$

# Content
d: ^\\src\\content\\blog$
d: ^\\src\\content\\docs$
d: ^\\src\\pages\\docs$
f: ^src\\pages\\terms\\.*\.md$

### Blog ###
# Your own files
```
